April 21, 2011

Holy crap, it's been forever. Sorry about that. Happy Easter, anyway. This release is mostly for maintenance, and features:

- A fix for a bug with track looping.
- Enhancements to the UI: it now uses the reusable CLI system that I developed for NM3.
- New licensing (same as NM3).
- A command to dump all audio samples from the ROM.
- Ability to set start and end points to trim MIDIs as well as just looping.

August 26, 2010

Sorry for the delay. This release enhances MIDI support. The new features:

- Certain metadata in MIDIs is now properly skipped (used to cause the converter to fail).
- Strange MIDI note-on and note-off messages are handled better: zero-volume note-ons are treated as note-offs; non-zero volume note-offs add to the warning count but are otherwise treated as normal note-offs.
- Several improvements to BPM handling. The converted song will typically be a bit smaller than before, and timing may be a tiny bit different (but it should never be noticeable, and is still accurate). Also, the BPM value used now follows the same convention as official GBA tracks.
- Converted midis can be set up to loop when you convert them. The loop will connect the end of the song to any specified offset (in "ticks" - 24ths of a beat) from the beginning.

The interface has changed slightly for converting MIDIs. You now specify the instrument offset separately with the 'offset' command, and just provide the song name to 'convert'. There are also commands 'loop' and 'noloop' used to control the looping.

June 11, 2010

Just some quick notes for the first release.

To run this program you will first need to install Python, if you haven't already. Don't mess around; get it right from the source - http://www.python.org/download . You want the current 2.x production version (as I write this, that's 2.6.5); I haven't written the code for compatibility with 3.x.

After you run the installer, all the file associations should be automatically set up for you, so just double-click cli.py (the main source file) to start.

This program has a command-line interface (hence "cli"), like the Windows 'cmd' command prompt or a Linux shell (or the Terminal on MacOS X). At the risk of insulting your intelligence: type the appropriate command (without quotes, and replacing stuff in angle brackets with whatever is described), then hit the Enter key and the program will do its thing. The 'help' command will tell you what commands are available and explain a little more about how the program works. 'help <command>' will give more detailed information on a command.

The version number is based off of my local VCS revision number. VCS = version control system. You should be using one of these to keep backups for your hack, if you aren't already. I'm planning to put a tutorial up on the FEU forum soon.

This is open-source software, released under the GPL, just like FEditor and Nightmare 2. Future tools might be slightly more restricted. Basically, the GPL (as I read it; I'm going to ask for clarification) technically lets you sell (charge money for) a redistribution of the software, which I don't agree with. It's not a big problem for the song editor (because it's specific enough that it doesn't have commercial value) but Nightmare 3 would be a whole other story.

The GPL license is provided in the file "COPYING", for reference. It's a plain-text file, despite the lack of a ".txt" extension. (It's named like that due to tradition. I thought about leaving the extension off for this file, too...)

Saved song files are in a raw binary format based off of how they are stored in the ROM. They contain the following pieces in order:

- The metadata struct, consisting of:
	- One word with a track count, two zero bytes and a count of used instruments (the burning code needs to know this). When the song is burned, the instrument count is erased and default values for priority and reverb are written in. For converted MIDIs, the instrument count is zero.
	- The location of the instrument map. For converted MIDIs, this is an absolute pointer value. (You should decide what ROM you're going to insert the MIDI into before converting it, or else you'll have to hex-edit this pointer manually after burning.) For ripped songs, it's an offset relative to *the start of the file*. (This also allows the burning code to find the end of the last track.)
Note that in the ROMs, the metadata normally comes AFTER the tracks. However, it doesn't really matter because of how the pointers in the metadata work.
	- The location of the start of each track. Each is an offset relative to *the start of the file*.

- The actual track data, in the same order as the original. Pointers within each track are replaced with an offset relative to *the current track*. Tracks that couldn't be burned are just skipped. The instrument IDs are modified to work with the "local instrument map" described below.

- Zero-padding to a word boundary.

Songs converted from MIDI end here.

- A "local instrument map" that only holds as many instrument structs as were actually used in the track. Percussion samples and individual instrument samples are mashed together. The first entry in the map represents the percurssion instrument, and is always 80 00 00 00 00 00 00 00 00 00 00 00. The sample pointers in the rest of the entries are converted into offsets relative to *the start of the sample data*; so the next one also always has a middle word of 00 00 00 00.

- The samples, in the same order as the local instrument map. Each is zero-padded to a word boundary.
